<script type="text/javascript"> erraiBusRemoteCommunicationEnabled = false; </script>
In some cases it might be desirable to prevent the client bus from communicating with the server. One use case for this is when all communication with the server is handled using JAX-RS and the constant long polling requests for message exchange are not needed.
To turn off remote communication in the client bus the following JavaScript variable can be set in the HTML host page:
<script type="text/javascript"> erraiBusRemoteCommunicationEnabled = false; </script>
By default the remote bus is expected at the GWT web application's context path. In case the remote bus is part of a different web application or deployed on a different server, the following configuration can be used in the HTML host page to configure the remote bus endpoint used on the client.
<script type="text/javascript"> erraiBusApplicationRoot = "/MyRemoteMessageBusEnpoint"; </script>
The ErraiService.properties file contains basic configuration for the bus itself. Unlike ErraiApp.properties, there should be at most one ErraiService.properties file on the classpath of a deployed application. If you do not need to set any properties to their non-default values, this file can be omitted from the deployment entirely.
Dispatchers encapsulate the strategy for taking messages that need to be delivered somewhere and seeing that they are delivered to where they need to go. There are two primary implementations that are provided with Errai, depending on your needs.
SimpleDispatcher is basic implementation that provides no asychronous delivery mechanism. Rather, when you configure the Errai to use this implementation, messages are delivered to their endpoints synchronously. The incoming HTTP thread will be held open until the messages are delivered.
While this sounds like it has almost no advantages, especially in terms of scalablity. Using the SimpleDispatcher can be far preferable when you're developing your application, as any errors and stack traces will be far more easily traced and some cloud services may not permit the use of threads in any case.
The AsyncDispatcher provides full asynchronous delivery of messages. When this dispatcher is used, HTTP threads will have control immediately returned upon dispatch of the message. This dispatcher provides far more efficient use of resources in high-load applications, and will significantly decrease memory and thread usage overall.
errai.dispatcher.implementation specifies the dispatcher implementation to be used by the bus. There are two implementations which come with Errai out of the box: the SimpleDispatcher and the AsyncDispatcher. See ERRAI:Dispatcher Implementations for more information about the differences between the two.
errai.async_thread_pool_size specifies the total number of worker threads in the worker pool for handling and delivering messages. Adjusting this value does not have any effect if you are using the SimpleDispatcher.
errai.async.worker_timeout specifies the total amount of time (in seconds) that a service is given to finish processing an incoming message before the pool interrupts the thread and returns an error. Adjusting this value has no effect if you are using the SimpleDispatcher.
errai.bus.buffer_size The total size of the transmission buffer, in megabytes. If this attribute is specified along with errai.bus.buffer_segment_count, then the segment count is inferred by the calculation buffer_segment_count / buffer_size}. If {{errai.bus.buffer_segment_count is also defined, it will be ignored in the presence of this property. Default value: 32.
errai.bus.buffer_segment_size The transmission buffer segment size in bytes. This is the minimum amount of memory each message will consume while stored within the buffer. Defualt value: 8.
errai.bus.buffer_segment_count The number of segments in absolute terms. If this attribute is specified in the absence of errai.bus.buffer_size, the buffer size is inferred by the calculation buffer_segment_size / buffer_segment_count.
errai.bus.buffer_allocation_mode Buffer allocation mode. Allowed values are direct and heap. Direct allocation puts buffer memory outside of the JVM heap, while heap allocation uses buffer memory inside the Java heap. For most situations, heap allocation is preferable. However, if the application is data intensive and requires a substantially large buffer, it is preferable to use a direct buffer. From a throughput perspective, current JVM implementations pay about a 20% performance penalty for direct-allocated memory access. However, your application may show better scaling characteristics with direct buffers. Benchmarking under real load conditions is the only way to know the optimal setting for your use case and expected load. Default value: direct.
errai.authentication_adapter specifies the authentication modelAdapter the bus should use for determining whether calls should be serviced based on authentication and security principals.
errai.require_authentication_for_all indicates whether or not the bus should always require the use of authentication for all requests inbound for the bus. If this is turned on, an authentication model adapter must be defined, and any user must be authenticated before the bus will deliver any messages from the client to any service.
errai.bus.enable_clustering A boolean indicating whether or not Errai's server side bus should attempt to orchestrate with its peers. The orchestration mechanism is dependent on the configured clustering provider (e.g. UDP based multicast discovery in case of the default JGroups provider). The default value is false.
errai.bus.clustering_provider The fully qualified class name of the clustering provider implementation. A class that implements org.jboss.errai.bus.server.cluster.ClusteringProvider. Currently the only build-in provider is the org.jboss.errai.bus.server.cluster.jgroups.JGroupsClusteringProvider.
errai.auto_discover_services A boolean indicating whether or not the Errai bootstrapper should automatically scan for services. This property must be set to true if and only if Errai CDI is not on the classpath. The default value is false.
errai.auto_load_extensions A boolean indicating whether or not the Errai bootstrapper should automatically scan for extensions. The default value is true.
## ## Request dispatcher implementation (default is SimpleDispatcher) ## #errai.dispatcher_implementation=org.jboss.errai.bus.server.SimpleDispatcher errai.dispatcher_implementation=org.jboss.errai.bus.server.AsyncDispatcher # ## Worker pool size. This is the number of threads the asynchronous worker pool should provide for processing ## incoming messages. This option is only valid when using the AsyncDispatcher implementation. ## errai.async.thread_pool_size=5 ## ## Worker timeout (in seconds). This defines the time that a single asychronous process may run, before the worker pool ## terminates it and reclaims the thread. This option is only valid when using the AsyncDispatcher implementation. ## errai.async.worker.timeout=5 ## ## Specify the Authentication/Authorization Adapter to use ## #errai.authentication_adapter=org.jboss.errai.persistence.server.security.HibernateAuthenticationAdapter #errai.authentication_adapter=org.jboss.errai.bus.server.security.auth.JAASAdapter ## ## This property indicates whether or not authentication is required for all communication with the bus. Set this ## to 'true' if all access to your application should be secure. ## #errai.require_authentication_for_all=true
Errai has several different implementations for HTTP traffic to and from the bus. We provide a universally-compatible blocking implementation that provides fully synchronous communication to/from the server-side bus. Where this introduces scalability problems, we have implemented many webserver-specific implementations that take advantage of the various proprietary APIs to provide true asynchrony.
These included implementations are packaged at: org.jboss.errai.bus.server.servlet.
You should use just one of the options below. Configuring multiple ErraiServlet implementations in the same application will lead to unpredictable behaviour!
Remember that all Errai demos and archetypes are preconfigured with DefaultBlockingServlet as a servlet. You will need to remove this default setup if you choose to use a different ErraiServlet implementation in your app.
All of the following examples use a wildcard mapping for *.erraiBus with no path prefix. This allows Errai Bus to communicate from any point in your application's URI hierarchy, which allows bus communication to work properly no matter where you choose to put your GWT host page.
For example, all of the following are equivalent from Errai's point of view:
/in.erraiBus
/foo/bar/in.erraiBus
/long/path/to/get/to.erraiBus
If you rely on your own security rules or a custom security filter to control access to Errai Bus (rather than the security framework within Errai Bus,) ensure you use the same mapping pattern for that filter-mapping or security-constraint as you do for the Errai Servlet itself.
This ErraiServlet implementation should work in virtually any servlet container that supports Java Servlets 2.0 or higher. It provides purely synchronous request handling. The one scenario where this servlet will not work is in servers that put restrictions on putting threads into sleep states.
The default DefaultBlockingServlet which provides the HTTP-protocol gateway between the server bus and the client buses.
As its name suggests, DefaultBlockingServlet is normally configured as an HTTP Servlet in the web.xml file:
<servlet>
<servlet-name>ErraiServlet</servlet-name>
<servlet-class>org.jboss.errai.bus.server.servlet.DefaultBlockingServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>ErraiServlet</servlet-name>
<url-pattern>*.erraiBus</url-pattern>
</servlet-mapping>
Alternatively, the DefaultBlockingServlet can be deployed as a Servlet Filter. This may be necessary in cases where an existing filter is configured in the web application, and that filter interferes with the Errai Bus
requests. In this case, configuring DefaultBlockingServlet to handle *.erraiBus requests ahead of other filters in web.xml will solve the problem:
<filter> <filter-name>ErraiServlet</filter-name> <filter-class>org.jboss.errai.bus.server.servlet.DefaultBlockingServlet</filter-class> </filter> <filter-mapping> <filter-name>ErraiServlet</filter-name> <url-pattern>*.erraiBus</url-pattern> </filter-mapping>
The Jetty implementation leverages Jetty's continuations support, which allows for threadless pausing of port connections. This servlet implementation should work without any special configuration of Jetty.
<servlet>
<servlet-name>ErraiServlet</servlet-name>
<servlet-class>org.jboss.errai.bus.server.servlet.JettyContinuationsServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>ErraiServlet</servlet-name>
<url-pattern>*.erraiBus</url-pattern>
</servlet-mapping>
This implementation leverages asynchronous support in Servlet 3.0 to allow for threadless pausing of port connections. Note that <async-supported>true</async-supported> has to be added to the servlet definition in web.xml.
<servlet>
<servlet-name>ErraiServlet</servlet-name>
<servlet-class>org.jboss.errai.bus.server.servlet.StandardAsyncServlet</servlet-class>
<load-on-startup>1</load-on-startup>
<async-supported>true</async-supported>
</servlet>
<servlet-mapping>
<servlet-name>ErraiServlet</servlet-name>
<url-pattern>*.erraiBus</url-pattern>
</servlet-mapping>